Bulk Top-Up

This API is used to add money or allowances to a prepaid balance of a rate plan (individual offer) for multiple subscribers in a single call.

The customer is not allowed to top-up a plan of the RATE type.

This is a Table Caption
HTTP URL
POST	/api/v2/bulk/subscriber/offer/topup

Eligibility

The requesting customer is allowed to top-up sub customers only. It is not allowed to top-up itself or top-up any other sub customer level.

API Request

Request Structure

Parameter	Type	M/O/CM	Description
bulk	Object	M	Array of main request body object.

Bulk data objects

Element	Type	M/O/CM	Description
subscriberIdentifiers	Object	M	Subscriber unique keys object, defines the search criteria
content	Object	M	Main elements container object

subscriberidentifiers data objects

Element	Type	M/O/CM	Description
type	String	M	Define the search criteria. ENUMs: IMSI, ICCID, MSISDN, IMEI
value	String	M	Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Parameter	Type	M/O/CM	Description
subscriberOfferingId	UUID	M	Subscriber offer ID
charge	Decimal	M	Top-up cost. Charge of post-paid balance
currency	String	M	Monetary currency. For example, USD, GBP, EUR
expirationDate	Date	O	Determines the requested date as per the selected expirationType set when plan created. Can be used only if the expirationType parameter has been set to FIXED.Ignored for other expirationType settings.
allowance	Object	CM	Array of allowance per serviceMandatory for plan of type USAGE’Ignored if filled in for plan of type MONEY

Allowance data objects

Element	Type	M/O/CM	Description
currency	String	M	Allowance: SMS: (Number of) SMSs \| Data: KB, MB, GB
value	Decimal	M	Balance amount

API Response

Response Structure

Parameter	Type	M/O/CM	Description
bulk	Object	M	Array of main response body object.
pageable	Object	O	Paging information object displayed when an API call was successful. For a failure, it will be empty.

Bulk data objects

Parameter	Type	M/O/CM	Description
errorCode	String	O	Failure code.
errorMessage	String	O	Failure message.
messageId	UUID	CM	Request instance ID. To be used by external systems to query the call (operation) status: In progress Successful Failed. Displayed when an API call was successful. For a failure, it will be empty.
subscriberIdentifiers	Object	M	Subscriber unique keys object, defines the search criteria.
content	Object	O	Main response body object that reflects a single node of the original request.

subscriberidentifiers data objects

Parameter	Type	M/O/CM	Description
type	String	M	Define the search criteria. ENUMs: IMSI, ICCID, MSISDN, IMEI
value	String	M	Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Parameter	Type	M/O/CM	Description
subscriberOfferingId	UUID	M	Subscriber offer ID
charge	Decimal	M	Top-up cost. Charge of post-paid balance
currency	String	M	Monetary currency. For example, USD, GBP, EUR
expirationDate	Date	O	Newly requested expiration date as per the selected expirationType set when plan created.
allowance	Object	CM	Array of allowance per service. Mandatory for plan of type USAGE. Ignored if filled in for plan of type MONEY.

Allowance data objects

Element	Type	M/O/CM	Description
Currency	String	M	Allowance: SMS: (Number of) SMSs Data: KB, MB, GB
value	Decimal	M	Balance amount

Pageable data objects

Element	Type	M/O/CM	Description
page	Numeric	M	Page number
size	Numeric	M	Page size. Number of requested elements per page
totalPages	Numeric	M	Total amount of available pages per requested page size
totalElements	Numeric	M	Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code	Message
GLOBAL_1001	Service unavailable. Please try again
SUBSCRIBER_1002	Subscriber does not exist
SUBSCRIBER_1009	Top-up failure. Balance not found
SUBSCRIBER_1013	Top-up failure. It is not allowed to top-up to pool plan using this API
SUBSCRIBER_1033	Ambiguous call. You have multiple offers. Please specify the requested offer ID

Examples

Request Body

Copy

{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "subscriberOfferingId": "e7fcef24-5c03-41dd-9e33-995b7d6f47b5",
        "charge": 20.5,
        "currency": "EUR",
        "expirationDate": "25042023",
        "allowance": [
          {
            "currency": "SMS",
            "value": 50
          }
        ]
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "subscriberOfferingId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
        "charge": 20.5,
        "currency": "EUR",
        "expirationDate": "25042023",
        "allowance": [
          {
            "currency": "MB",
            "value": 20
          }
        ]
      }
    }
  ]
}

Response Body: Full Success (ACK)

Copy

{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "subscriberOfferingId": "e7fcef24-5c03-41dd-9e33-995b7d6f47b5",
        "charge": 20.5,
        "currency": "EUR",
        "expirationDate": "25042023",
        "allowance": [
          {
            "currency": "SMS",
            "value": 50
          }
        ]
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000035687"
      },
      "content": {
        "subscriberOfferingId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
        "charge": 20.5,
        "currency": "EUR",
        "expirationDate": "25042023",
        "allowance": [
          {
            "currency": "MB",
            "value": 20
          }
        ]
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body: Includes Failure(s) (NAK)

Copy

{
  "bulk": [
    {
      "errorCode": "SUBSCRIBER_1009",
      "errorMessage": "Top-up failure. Balance not found",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "subscriberOfferingId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
        "charge": 20.5,
        "currency": "EUR",
        "expirationDate": "25042023",
        "allowance": [
          {
            "currency": "MB",
            "value": 20
          }
        ]
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}